The coveralls npm package is used to integrate your project with Coveralls, a web service that provides test coverage history and statistics. It helps developers ensure that their code is well-tested by tracking the percentage of code covered by tests over time.
Sending Coverage Reports
This feature allows you to send your test coverage reports to Coveralls. The code sample reads the coverage report from a file and sends it to Coveralls using the `handleInput` method.
const coveralls = require('coveralls');
const fs = require('fs');
fs.readFile('coverage/lcov.info', 'utf8', (err, data) => {
if (err) {
console.error('Error reading coverage file:', err);
return;
}
coveralls.handleInput(data, (err) => {
if (err) {
console.error('Error sending to Coveralls:', err);
} else {
console.log('Coverage report sent to Coveralls');
}
});
});Custom Git Information
This feature allows you to send custom Git information along with your coverage report. The code sample demonstrates how to include custom Git metadata when sending the coverage report to Coveralls.
const coveralls = require('coveralls');
const fs = require('fs');
const gitInfo = {
head: {
id: 'commit-sha',
author_name: 'Author Name',
author_email: 'author@example.com',
committer_name: 'Committer Name',
committer_email: 'committer@example.com',
message: 'Commit message'
},
branch: 'main'
};
fs.readFile('coverage/lcov.info', 'utf8', (err, data) => {
if (err) {
console.error('Error reading coverage file:', err);
return;
}
coveralls.handleInput(data, { git: gitInfo }, (err) => {
if (err) {
console.error('Error sending to Coveralls:', err);
} else {
console.log('Coverage report with custom git info sent to Coveralls');
}
});
});Codecov is another popular service for tracking code coverage. It provides similar functionalities to Coveralls, such as integrating with CI/CD pipelines and supporting multiple languages and coverage formats. Codecov also offers additional features like detailed coverage graphs and pull request comments.
NYC is a command-line tool for generating code coverage reports. It is often used in conjunction with other tools like Mocha or Jest. While NYC itself does not provide a web service for tracking coverage history, it can be used to generate coverage reports that can then be sent to services like Coveralls or Codecov.
Jest is a JavaScript testing framework that includes built-in support for generating code coverage reports. While Jest focuses more on testing, it can be configured to output coverage reports in formats compatible with services like Coveralls and Codecov.
Coveralls.io support for node.js. Get the great coverage reporting of coveralls.io and add a cool coverage button ( like the one above ) to your README.
Supported CI services: travis-ci, codeship, circleci, jenkins, Gitlab CI
Add the latest version of coveralls to your package.json:
npm install coveralls --save-dev
If you're using mocha, add mocha-lcov-reporter to your package.json:
npm install mocha-lcov-reporter --save-dev
This script ( bin/coveralls.js ) can take standard input from any tool that emits the lcov data format (including mocha's LCov reporter) and send it to coveralls.io to report your code coverage there.
Once your app is instrumented for coverage, and building, you need to pipe the lcov output to ./node_modules/coveralls/bin/coveralls.js.
This library currently supports travis-ci with no extra effort beyond piping the lcov output to coveralls. However, if you're using a different build system, there are a few environment variables that are necessary:
There are optional environment variables for other build systems as well:
NODE_ENV=test YOURPACKAGE_COVERAGE=1 ./node_modules/.bin/mocha \
--require blanket \
--reporter mocha-lcov-reporter | ./node_modules/coveralls/bin/coveralls.js
Instrumenting your app for coverage is probably harder than it needs to be (read here), but that's also a necessary step.
In mocha, if you've got your code instrumented for coverage, the command for a travis build would look something like this:
YOURPACKAGE_COVERAGE=1 ./node_modules/.bin/mocha test -R mocha-lcov-reporter | ./node_modules/coveralls/bin/coveralls.js
Check out an example Makefile from one of my projects for an example, especially the test-coveralls build target. Note: Travis runs npm test, so whatever target you create in your Makefile must be the target that npm test runs (This is set in package.json's 'scripts' property).
With Mocha:
istanbul cover ./node_modules/mocha/bin/_mocha --report lcovonly -- -R spec && cat ./coverage/lcov.info | ./node_modules/coveralls/bin/coveralls.js && rm -rf ./coverage
With Jasmine:
istanbul cover jasmine-node --captureExceptions spec/ && cat ./coverage/lcov.info | ./node_modules/coveralls/bin/coveralls.js && rm -rf ./coverage
Depend on nodeunit, jscoverage and coveralls:
npm install nodeunit jscoverage coveralls --save-dev
Add a coveralls script to "scripts" in your package.json:
"scripts": {
"test": "nodeunit test",
"coveralls": "jscoverage lib && YOURPACKAGE_COVERAGE=1 nodeunit --reporter=lcov test | coveralls"
}
Ensure your app requires instrumented code when process.env.YOURPACKAGE_COVERAGE variable is defined.
Run your tests with a command like this:
npm run coveralls
For detailed instructions on requiring instrumented code, running on Travis and submitting to coveralls see this guide.
Client-side JS code coverage using PhantomJS, Mocha and Blanket:
data-cover html-attribute./node_modules/.bin/poncho -R lcov test/test.html | ./node_modules/coveralls/bin/coveralls.js
lab -r lcov | ./node_modules/.bin/coveralls
works with almost any testing framework. Simply execute
npm test with the nyc bin followed by running its reporter:
nyc npm test && nyc report --reporter=text-lcov | coveralls
Simply run your tap tests with the COVERALLS_REPO_TOKEN environment
variable set and tap will automatically use nyc to report
coverage to coveralls.
Usage: coveralls.js [-v] filepath
-v, --verbose
filepath - optionally defines the base filepath of your source files.
If you're running locally, you must have a .coveralls.yml file, as documented in their documentation, with your repo_token in it; or, you must provide a COVERALLS_REPO_TOKEN environment-variable on the command-line.
If you want to send commit data to coveralls, you can set the COVERALLS_GIT_COMMIT environment-variable to the commit hash you wish to reference. If you don't want to use a hash, you can set it to HEAD to supply coveralls with the latest commit data. This requires git to be installed and executable on the current PATH.
I generally don't accept pull requests that are untested, or break the build, because I'd like to keep the quality high (this is a coverage tool afterall!).
I also don't care for "soft-versioning" or "optimistic versioning" (dependencies that have ^, x, > in them, or anything other than numbers and dots). There have been too many problems with bad semantic versioning in dependencies, and I'd rather have a solid library than a bleeding edge one.
FAQs
takes json-cov output into stdin and POSTs to coveralls.io
The npm package coveralls receives a total of 461,966 weekly downloads. As such, coveralls popularity was classified as popular.
We found that coveralls demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 2 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
An advanced npm supply chain attack is leveraging Ethereum smart contracts for decentralized, persistent malware control, evading traditional defenses.
Security News
Research
Attackers are impersonating Sindre Sorhus on npm with a fake 'chalk-node' package containing a malicious backdoor to compromise developers' projects.
Security News
The npm package for the LottieFiles Player web component was hit with a supply chain attack after a software engineer's npmjs credentials were compromised.